home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Shareware Grab Bag
/
Shareware Grab Bag.iso
/
007
/
lpmac1.arc
/
MACROS.DOC
< prev
next >
Wrap
Text File
|
1987-03-03
|
25KB
|
643 lines
Documentation for MACROS.MLB Page 1
TABLE OF CONTENTS
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . 2
CONVENTIONS, OPENING MACROS AND CLOSING MACROS . . . . . . . 3
LISTING CONTROL . . . . . . . . . . . . . . . . . . . . 3
OUT_UNNECESSARY_LONG_COMMENTS - Closing summary macro . 3
BLANK MACRO ARGUMENTS . . . . . . . . . . . . . . . . . 3
CONVENTIONS IN THIS DOCUMENTATION . . . . . . . . . . . 4
A STRATEGY TO MINIMIZE THE NUMBER OF LONG JUMPS . . . . . . 5
JUMPS TO EXPLICIT LABELS . . . . . . . . . . . . . . . . . . 6
GENERAL . . . . . . . . . . . . . . . . . . . . . . . . 6
LJMP TARGET_LABEL, LONG - Unconditional jump to
TARGET_LABEL. . . . . . . . . . . . . . . . . . . 6
LCJMP CONDITION-1, TARGET_LABEL, LONG - Conditional
jump to TARGET_LABEL. . . . . . . . . . . . . . . 6
LJCXZ TARGET_LABEL, LONG - Jump to TARGET_LABEL if
register CX is zero. . . . . . . . . . . . . . . . 6
LLOOP CONDITION-3, TARGET_LABEL, LONG - Conditional and
unconditional loops. . . . . . . . . . . . . . . . 6
STRUCTURED MACROS . . . . . . . . . . . . . . . . . . . . . 7
GENERAL . . . . . . . . . . . . . . . . . . . . . . . . 7
Jump to the beginning or the end of an "enclosing
block" . . . . . . . . . . . . . . . . . . . . . . 8
BEGIN and END . . . . . . . . . . . . . . . . . . . . . 9
IF and IF - ELSE with one condition . . . . . . . . . . 9
IF and IF - ELSE with multiple AND conditions . . . . . 10
Repetition for a count . . . . . . . . . . . . . . . . 11
WHILE . . . . . . . . . . . . . . . . . . . . . . . . . 12
REPEAT UNTIL . . . . . . . . . . . . . . . . . . . . . 12
REPEAT FOREVER . . . . . . . . . . . . . . . . . . . . 12
OTHER MACROS . . . . . . . . . . . . . . . . . . . . . . . . 13
Multiple PUSH and POP . . . . . . . . . . . . . . . . . 13
Show the state of the Zero Flag in AL . . . . . . . . . 13
NOTZ - Toggle the Zero Flag . . . . . . . . . . . . . . 13
Call procedures which use a string whose OFFSET is in
either BX or DX . . . . . . . . . . . . . . . . . 13
Call a procedure which uses a File Control Block . . . 14
Documentation for MACROS.MLB Page 2
I. INTRODUCTION
I based this collection of macros for MicroSoft MASM on
MACROS.MLB in the public domain file HERSHMAC.ARC, which Mark
Hersey of Hersey Micro Consulting, Inc. wrote. I made enough
changes so that I can not claim that his work created any
problems you might find with it.
HERSHMAC.ARC also includes the following files which define
symbolic constants:
CHARS.MLB contains constant declarations for ASCII
characters.
I8086.MLB contains constant declarations which are for
use with an 8086 assembler.
MSDOS.MLB contains constant declarations which are for
use with Seattle Computer Products MS-DOS operating system.
They seem useable for Microsoft's PC-DOS also.
I have tried to be sure that MACROS.MLB and these three files do
not depend on one another. I have included them in this ARChive.
Michael Abrash's article "Conditional-jump Macros" in the
February, 1987 issue of "PC Tech Journal" inspired the macros
which begin with the letter L and give various forms of jump and
loop instructions.
Since I am placing these macros in the public domain, I am
not responsible for any bad things which they might do.
Lew Paper
10:53 am on 3/1/87
Documentation for MACROS.MLB Page 3
II. CONVENTIONS, OPENING MACROS AND CLOSING MACROS
A. LISTING CONTROL
MASM allows three kinds of listing for macro expansions.
.LALL lists code and ";" comments; .XALL lists code only; .SALL
surpresses all listing. The default is .XALL.
MACROS.MLB uses the macro variable MACRO_EXPANSION_CONTROL
to specify which level you want. If it is not defined, it
assumes .XALL, which is consistent with the MASM default. Its
definitions are:
0 for .XALL (list code only)
1 for .SALL (surpress all listing)
2 for .LALL (list code and comments).
Any other value also gives .XALL.
The macro SET_MACRO_EXPANSION actually sets MASM's listing
control according to to the value in MACRO_EXPANSION_CONTROL.
As discussed below, a long jump to a forward label which
could be short will generate a comment. MACROS.MLB needs
something like MACRO_EXPANSION_CONTROL to reset itself
afterwards.
B. OUT_UNNECESSARY_LONG_COMMENTS - Closing summary macro
Use the macro OUT_UNNECESSARY_LONG_COMMENTS, which has no
arguments, at the end of any file which uses any of the macros
described in Section III, JUMPS TO EXPLICIT LABELS or Section IV,
STRCTURED MACROS with a LONG argument. It will add a comment if
there are any unnecessary long forward jumps and also print a
message to that effect on the screen. It does nothing if there
are none.
Strictly speaking, you only need to use
OUT_UNNECESSARY_LONG_COMMENTS if you have a forward long jump.
Rather than worry about whether a structured macro is forward or
backward, it is easier to use it in any case where it might come
into play.
C. BLANK MACRO ARGUMENTS
Indicate that all arguments of a macro are blank by not
entering a macro list. Indicate that the last argument of a
macro is blank by ending the argument list with the last
non-blank argument. Indicate that the first argument of a macro
is blank by starting the macro list with a comma. Indicate that
an internal argument of a macro is blank by entering just a comma
following the preceding comma.
Documentation for MACROS.MLB Page 4
CONVENTIONS, OPENING MACROS AND CLOSING MACROS (Continued)
D. CONVENTIONS IN THIS DOCUMENTATION
CONDITION-1 is a completion to any conditional jump J
instruction except JCXZ. Its legal values are:
A, AE, B, BE, C, E, G, GE, L, LE, NA, NAE, NB, NBE, NC,
NE, NG, NGE, NL, NLE, NO, NP, NS, NZ, O, P, PE, PO, S, Z.
CONDITION-2 is a completion to any condition jump J
instruction which tests flags affected by an OR instruction
except JCXZ. The values for which it gives a choice are:
BE, E, G, GE, L, LE, NA, NE, NG, NGE, NL, NLE, NP, NS,
NZ, P, PE, PO, S, Z.
It is always true, so probably not useful, for:
A, AE, NB, NBE, NC, NO.
It is always false, so probably not useful, for:
B, C, O, NAE.
CONDITION-3 is a completion to any LOOP instruction. Its
legal values are:
blank, E, NE, NZ, Z.
VAR1, CONDITION, VAR2 has two meanings. If VAR2 is blank,
it means, "AND VAR1, VAR1", then jump on CONDITION-2. Since the
8086 does not allow "AND mem, mem", this option only works if
VAR1 is a register. If VAR2 is not blank, it means,
"CMP VAR1, VAR2", then jump on CONDITION-1. Since the 8086 does
not allow "CMP mem1, mem2", this option requires that either VAR1
or VAR2 be either a register or an immediate variable. Most of
the macros have a form which jumps on a condition which is
already set. In those cases, you are free to set it by any
operation you want.
LONG forces MASM to compile a long forward jump if it is not
blank. It is always the last argument. Anything in this
position will do, but the word "long" could clarify your meaning.
Incidentally, MACROS.MLB ignores LONG for a backward jump.
Documentation for MACROS.MLB Page 5
III. A STRATEGY TO MINIMIZE THE NUMBER OF LONG JUMPS
MASM can determine whether a backward jump is long or short
on pass 1, but it can't do the same thing for forward jumps. The
LONG argument is the way the macros below respond to this
problem.
One general strategy which you coud follow to assure
yourself that there are no unnecessary long jumps is:
Compile with no LONG arguments.
If there are any "Relative jump out of range"
error messages, add a LONG argument to those macros and
compile again.
Repeat the last step until there are no "Relative
jump out of range" error messages.
Since each LONG adds some bytes, it is possible that adding
a LONG argument will spread out another forward jump so it must
be long. You can cook up some very intertwined examples which
would take many cycles to clear up, but usually there shouldn't
be too many recyclings.
If you are sure that a forward jump will exceed 127 bytes,
you could use a LONG argument immediately. If you are wrong, you
will get a comment which tells you that that particular jump
doesn't need to be long. If this happens, I suggest that you use
the pure general strategy which I outlined above.
Documentation for MACROS.MLB Page 6
IV. JUMPS TO EXPLICIT LABELS
A. GENERAL
MASM can determine whether a backward jump is long or short
on pass 1. It can't do the same thing for a forward jump, but it
can tell on pass 2 if a long forward jump could have been short.
These macros take advantage of those abilities.
Each of them jump or loop to the argument target_label. For
backward jumps, each of them either issues a short jump or else
one or more instructions which give the same conditional effect
if any and issue a long jump.
For forward jumps, they all use the variable LONG, which I
described in Section II-D above. MASM will flag short forward
jumps which should have been long as an error 53, "Relative jump
out of range." Each of these macros write a comment, "******
This jump doesn't need to be LONG ******" for a long forward jump
which could have been short.
See Section III above for a strategy which minimizes the
number of long jumps.
B. LJMP TARGET_LABEL, LONG - Unconditional jump to TARGET_LABEL.
C. LCJMP CONDITION-1, TARGET_LABEL, LONG - Conditional jump to
TARGET_LABEL.
CONDITION-1 is the conditional part of any J? operation
except JCXZ. See Section II-D above for a complete list.
D. LJCXZ TARGET_LABEL, LONG - Jump to TARGET_LABEL if register
CX is zero.
E. LLOOP CONDITION-3, TARGET_LABEL, LONG - Conditional and
unconditional loops.
Use "LLOOP ,TARGET_LABEL, LONG" for an unconditional loop.
See Section II-C for a discussion of blank macro arguments.
Otherwise, E, NE, NZ, Z are legal values for CONDITION-3.
Documentation for MACROS.MLB Page 7
V. STRUCTURED MACROS
A. GENERAL
Structured macros are combinations of macros which produce
the effects of structured programming. They generate their own
labels, which have the form L?n, where n is a number which is
more or less sequential. They can be nested almost indefinitely.
They use all of the long and short features of jumps to
explicit labels discussed in Section III-A above. If a component
macro includes a forward jump, its arguments will terminate with
LONG. See Section III above for a strategy which minimizes the
number of long jumps.
See Section II-D for descriptions of arguments not
explicitly described with the structured macro.
The list of structured macros below is probably not
complete. You can use the source code to build other
combinations to fit your particular needs.
Documentation for MACROS.MLB Page 8
STRUCTURED MACROS (Continued)
B. Jump to the beginning or the end of an "enclosing block"
I will define the term "enclosing block" to mean a pair of
macros which establish internal labels at the start of the first
one and after the second one. Several of the macro combinations
discussed below form enclosing blocks. The following macros will
jump to the beginning or past the end of any of them:
XNEXT LONG ; Unconditionally jump to the
; beginning of the block
XCNEXT VAR1, CONDITION, VAR2, LONG
; Set condition then conditionally
; jump to the beginning of the
; block
XCNEXTC CONDITION-1, LONG
; Jump to the beginning of the
; block based on the condition when
; you invoke the macro
XEXIT LONG ; Unconditionally jump to beyond
; the end of the block
XCEXIT VAR1, CONDITION, VAR2, LONG
; Set condition then conditionally
; jump to beyond the end of the
; block
XCEXITC CONDITION-1 LONG
; Jump to beyond the end of the
; block based on the condition when
; you invoke the macro
You can use these macros outside of an enclosing block. The
NEXT macros will look for the internal label with the next
sequential number, and the EXIT macros will look for the internal
label with the current sequential number plus 2. There are
enough possibilities so that their effect is somewhat
unpredicable. I suggest a jump to an explicit label instead.
If these macros are used inside of an enclosing block,
XEXIT, XCEXIT and XCEXITC include forward jumps.
Each section will say whether its macros form an enclosing
block.
Documentation for MACROS.MLB Page 9
STRUCTURED MACROS (Continued)
C. BEGIN and END
XBEGIN
body
XEND
BEGIN and END form an enclosing block with no other effects.
D. IF and IF - ELSE with one condition
XIF VAR1, CONDITION, VAR2, LONG
body
XENDIF
If you want to set CONDITION-1 before you invoke XIF,
replace the XIF line with
XIFC CONDITION-1, LONG
Each of these forms allows an optional ELSE clause. For
example, the first form becomes:
XIF VAR1, CONDITION, VAR2, LONG
body-1
XELSE LONG
body-2
XENDIF
XIF, XIFC and XELSE each include forward jumps.
XIF and XENDIF form an enclosing block as long as there is
no XELSE between them. If there is an XELSE between them, they
do not form and enclosing block. For this reason, it is probably
safer to use XBEGIN and XEND around body-1 and/or body-2 if you
want any form of XNEXT or XEXIT.
Documentation for MACROS.MLB Page 10
STRUCTURED MACROS (Continued)
E. IF and IF - ELSE with multiple AND conditions
XIF VAR1, CONDITION, VAR2, LONG
XANDIF VAR1, CONDITION, VAR2, LONG
; The two invocations should have
; at least one of VAR1, CONDITION
; and VAR2 different to be useful.
body
XENDIF
You must first use exactly one XIF. You can then use more
than one XANDIF.
You can use both XIFC and XELSE as above in this form. In
addition, you can set CONDITION-1 for an XANDIF and replace it
with
XANDIFC CONDITION-1, LONG
XANDIF and XANDIFC each include forward jumps.
XIF or XIFC and XENDIF form an enclosing block as long as
there is no XELSE between them. If there is an XELSE between
them, they do not form and enclosing block. For this reason, it
is probably safer to use XBEGIN and XEND around body-1 and/or
body-2 if you want any form of XNEXT or XEXIT.
Documentation for MACROS.MLB Page 11
STRUCTURED MACROS (Continued)
F. Repetition for a count
Enter with CX set to the maximum number of times to repeat.
XFOR NOZERO, LONG
; If NOZERO is blank, skip the body
; of the loop if CX starts as zero.
; If it exists, always repeat at
; least once.
body
XDEC CONDITION-3
; End of loop
The value of NOZERO doesn't matter. For documentation, you
might consider using nozero.
LONG is only useful if NOZERO is blank. The three useful
configurations of the FOR line are:
FOR
FOR nozero
FOR , long
CONDITION-3 can be blank for an unconditional loop or E, NZ,
NE or Z for a conditional loop. See Section II-D for more
information on CONDITION-3.
If NOZERO is blank, XFOR contains a forward jump. If it is
not blank, XFOR does not contain a forward jump.
XFOR and XDEC form an enclosing block. XNEXT does not
change the number of repetitions. If you want to bypass part of
the processing for this repetition but keep on counting, enclose
body with XBEGIN and XEND and then use XEXIT.
Documentation for MACROS.MLB Page 12
STRUCTURED MACROS (Continued)
G. WHILE
XWHILE VAR1, CONDITION, VAR2, LONG
; Terminate loop if CONDITION-1
body
XENDLP ; End this pass through the loop
If you want to initialize CONDITION-1 before entering and
set it in body for the next pass through the loop, replace the
XWHILE line with
XWHILEC CONDITION-1, LONG
; Terminate loop if CONDTION-1
XEXIT and XEXITC include forward jumps.
XWHILE or XWHILEC and XENDLP form an enclosing block.
H. REPEAT UNTIL
XREPEAT ; Start of loop
body
XUNTIL VAR1, CONDITION, VAR2
; End this pass through the loop
If you want to set CONDITION-1 in body, replace the XUNTIL
line with
XUNTILC CONDITION-1 ; End this pass through the loop
XREPEAT and XUNTIL or XUNTILC form an enclosing block.
XNEXT does not test CONDITION-1. If you want to bypass part of
the processing for this repetition but still test, enclose body
with XBEGIN and XEND and then use XEXIT.
I. REPEAT FOREVER
XLOOP
body
XENDLP
body should include some form of XEXIT.
XLOOP and XENDLP form an enclosing block.
NOTE: XLOOP is a synonym for XREPEAT.
Documentation for MACROS.MLB Page 13
VI. OTHER MACROS
A. Multiple PUSH and POP
PUSH_REGISTER <REGISTER LIST> pushes the list of registers
contained in REGISTER LIST on the program stack and saves what it
has done for POP_REGISTER.
POP_REGISTER pops the registers saved by PUSH_REGISTER in
the proper order.
PUSHM <LIST> pushes the registers and memory locations
contained in LIST on the program stack in the same order as LIST.
POPM <LIST> pops the registers and memory locations
contained in LIST from the program stack in the same order as
LIST. If it is used with PUSHM, the two LIST's should be in
reversed order.
The angle brackets in PUSH_REGISTER, PUSHM and POPM are
required.
B. Show the state of the Zero Flag in AL
GETZ sets AL to TRUE if the Zero Flag is set and to FALSE if
it is not set.
GETNZ sets AL to TRUE if the Zero Flag is not set and to
FALSE if it is set.
C. NOTZ - Toggle the Zero Flag
D. Call procedures which use a string whose OFFSET is in either
BX or DX
CALLSTR ROUTINE, STRING
where
ROUTINE is the name of the procedure to call.
STRING is the name of a string whose OFFSET should go
into register DX.
GETCALL ROUTINE, STRING
where
ROUTINE is the name of the procedure to call.
STRING is the name of a string whose OFFSET should go
into register BX.
Documentation for MACROS.MLB Page 14
OTHER MACROS (Continued)
E. Call a procedure which uses a File Control Block
FCBCALL ROUTINE, FCB, ERRORRTN
where
ROUTINE is the name of the procedure to call. It
should set the Zero Flag if there is an error.
FCB is the name of the File Control Block.
ERRORRTN is the optional name of an error procedure
which the program will call if the Zero Flag is set.
